Skunkware 5/Skunkware 5.iso/man/cat.1/tknewsbiff.1

Text File | 1995-07-25 | 23KB | 529 lines

     TTTTKKKKNNNNEEEEWWWWSSSSBBBBIIIIFFFFFFFF((((1111))))    UUUUNNNNIIIIXXXX SSSSyyyysssstttteeeemmmm VVVV ((((1111 JJJJaaaannnnuuuuaaaarrrryyyy 1111999999994444))))     TTTTKKKKNNNNEEEEWWWWSSSSBBBBIIIIFFFFFFFF((((1111))))



     NNNNAAAAMMMMEEEE
          tknewsbiff - pop up a window when news appears

     SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
          ttttkkkknnnneeeewwwwssssbbbbiiiiffffffff [ _s_e_r_v_e_r _o_r _c_o_n_f_i_g-_f_i_l_e ]

     IIIINNNNTTTTRRRROOOODDDDUUUUCCCCTTTTIIIIOOOONNNN
          ttttkkkknnnneeeewwwwssssbbbbiiiiffffffff pops up a window when there is unread news in
          your favorite newsgroups and removes the window after you've
          read the news.  tknewsbiff can optionally play a sound,
          start your newsreader, etc.


     SSSSEEEELLLLEEEECCCCTTTTIIIINNNNGGGG NNNNEEEEWWWWSSSSGGGGRRRROOOOUUUUPPPPSSSS
          By default, the configuration file ~/.tknewsbiff describes
          how tknewsbiff behaves.  The syntax observes the usual Tcl
          rules - however, even if you don't know Tcl, all but the
          most esoteric configurations will be obvious.

          Each newsgroup (or set of newsgroups) to be watched is
          described by using the "watch" command.  For example:


          watch dc.dining
          watch nist.*
          watch comp.unix.wizard  -threshold 3
          watch *.sources.*       -threshold 20


          For each newsgroup pattern, any newsgroup that matches it
          and which you are subscribed to (according to your newsrc
          file) is eligible for reporting.  By default, tknewsbiff
          reports on the newsgroup if there is at least one unread
          article.  The "-threshold" flag changes the threshold to the
          following number.  For example, "-threshold 3" means there
          must be at least three articles unread before tknewsbiff
          will report the newsgroup.

          If no watch commands are given (or no configuration file
          exists), all groups which are subscribed to are watched.

          To suppress newsgroups that would otherwise be reported, use
          the "ignore" command.  For example, the following matches
          all comp.* and nist.* newgroups except for nist.posix or .d
          (discussion) groups:


          watch comp.*
          watch nist.*
          ignore nist.posix.*
          ignore *.d




     Page 1                                          (printed 7/23/95)






     TTTTKKKKNNNNEEEEWWWWSSSSBBBBIIIIFFFFFFFF((((1111))))    UUUUNNNNIIIIXXXX SSSSyyyysssstttteeeemmmm VVVV ((((1111 JJJJaaaannnnuuuuaaaarrrryyyy 1111999999994444))))     TTTTKKKKNNNNEEEEWWWWSSSSBBBBIIIIFFFFFFFF((((1111))))



          The flag "-new" describes a command to be executed when the
          newsgroup is first reported as having unread news.  For
          example, the following lines invoke the UNIX command "play"
          to play a sound.


          watch dc.dining -new "exec play /usr/local/sounds/yumyum.au"
          watch rec.auto* -new "exec play /usr/local/sounds/vroom.au"


          You can cut down on the verbosity of actions by defining
          procedures.  For example, if you have many -new flags that
          all play sound files, you could define a sound procedure.
          This would allow the -new specification to be much shorter.


          proc play {sound} {
               exec play /usr/local/sounds/$sound.au
          }

          watch dc.dining -new "play yumyum"
          watch rec.auto* -new "play vroom"


          As an aside, you can put an "&" at the end of an "exec"
          command to get commands to execute asynchronously.  However,
          it's probably not a good idea to do this when playing sound
          files anyway.

          "newsgroup" is a read-only variable which contains the name
          of the newsgroup that is being reported.  This is useful
          when the action is triggered by a pattern.  For example, the
          following line could run the newsgroup name through a speech
          synthesizer:


          watch * -new {
               exec play herald.au
               exec speak "New news has arrived in $newsgroup."
          }


          The flag "-display" describes a command to be executed every
          time the newsgroup is reported as having unread news.  The
          special command "display" is the default command.  It
          schedules $newsgroup to be written to tknewsbiff's display
          when it is rewritten.  For example, by explicitly providing
          a -display flag that omits the display command, you can
          disable the display of newsgroups that are already reported
          via -new.





     Page 2                                          (printed 7/23/95)






     TTTTKKKKNNNNEEEEWWWWSSSSBBBBIIIIFFFFFFFF((((1111))))    UUUUNNNNIIIIXXXX SSSSyyyysssstttteeeemmmm VVVV ((((1111 JJJJaaaannnnuuuuaaaarrrryyyy 1111999999994444))))     TTTTKKKKNNNNEEEEWWWWSSSSBBBBIIIIFFFFFFFF((((1111))))



          watch dc.dining -new {exec play yumyum.au} -display {}


          If you want to execute an action repeatedly and _s_t_i_l_l
          display the newsgroup in the default manner, explicitly
          invoke the display command via the -display flag.  For
          example:


          watch *security* -display {
               exec play red-alert.au
               display
          }


          Actions associated with the -new and -display flags are
          executed only once for each matching newsgroup.  The command
          executed is the one associated with the first pattern in the
          configuration file that matches and observes the given
          threshold.

          Any command that is simply listed in the configuration file
          is executed each time before the update loop in tknewsbiff.
          The reserved (but user-defined) procedure "user" is run
          immediately after the newsgroups are scheduled to be written
          to the display and before they are actually written.

          For example, suppose unread articles appear in several
          rec.auto groups and you play the same sound for each one.
          To prevent playing the sound several times in a row, make
          the -new command simply set a flag.  In the user procedure,
          play the sound if the flag is set (and then reset the flag).

          The user procedure could also be used to start a newsreader.
          This would avoid the possibility of starting multiple
          newsreaders just because multiple newsgroups contained
          unread articles.  (A check should, of course, be made to
          make sure that a newsreader is not already running.)


     MMMMOOOORRRREEEE VVVVAAAARRRRIIIIAAAABBBBLLLLEEEESSSS
          The following example lines show variables that can affect
          the behavior of tknewsbiff


          set delay          120
          set server         news.nist.gov
          set server_timeout 60
          set newsrc         ~/.newsrc
          set width          40
          set height         20
          set active_file    /usr/news/lib/active



     Page 3                                          (printed 7/23/95)






     TTTTKKKKNNNNEEEEWWWWSSSSBBBBIIIIFFFFFFFF((((1111))))    UUUUNNNNIIIIXXXX SSSSyyyysssstttteeeemmmm VVVV ((((1111 JJJJaaaannnnuuuuaaaarrrryyyy 1111999999994444))))     TTTTKKKKNNNNEEEEWWWWSSSSBBBBIIIIFFFFFFFF((((1111))))



          tknewsbiff alternates between checking for unread news and
          sleeping (kind of like many undergraduates).  The "delay"
          variable describes how many seconds to sleep.

          The "server" variable names an NNTP news-server.  The
          default is "news".  The "server" variable is only used if
          the "active_file" variable is not set.

          The "server_timeout" variable describes how how many seconds
          to wait for a response from the server before giving up.  -1
          means wait forever or until the server itself times out.
          The default is 60 seconds.

          The "newsrc" variable describes the name of your .newsrc
          file.  By default, tknewsbiff looks in your home directory
          for a newsrc file.  A server-specific newsrc is used if
          found.  For example, if you have set server to
          "cubit.nist.gov", then tknewsbiff looks for ~/.newsrc-
          cubit.nist.gov.  (This is the Emacs gnus convention - which
          is very convenient when you read news from multiple
          servers.)  If there is no server-specific newsrc, tknewsbiff
          uses ~/.newsrc.

          The "width" variable describes the width that tknewsbiff
          will use to display information.  If any newsgroup names are
          long enough, they will be truncated so that the article
          counts can still be shown.  You can manually resize the
          window to see what was truncated.  However, if your
          configuration file sets the width variable, the window will
          be restored to that size the next time that tknewsbiff
          checks for unread news and updates its display.

          The "height" variable describes the maximum height that
          tknewsbiff will use to display information.  If fewer
          newsgroups are reported, tknewsbiff will shrink the window
          appropriately.  You can manually resize the window but if
          your configuration file sets the height variable, the window
          will be restored to that size the next time that tknewsbiff
          checks for unread news and updates its display.

          The "active_file" variable describes the name of the news
          active file.  If set, the active file is read directly in
          preference to using NNTP (even if the "server" variable is
          set).  This is particularly useful for testing out new
          configuration files since you can edit a fake active file
          and then click button 2 to immediately see how tknewsbiff
          responds (see BUTTONS below).

          If the environment variable DOTDIR is set, then its value is
          used as a directory in which to find all dotfiles instead of
          from the home directory.  In particular, this affects the
          tknewsbiff configuration file and the .newsrc file (assuming



     Page 4                                          (printed 7/23/95)






     TTTTKKKKNNNNEEEEWWWWSSSSBBBBIIIIFFFFFFFF((((1111))))    UUUUNNNNIIIIXXXX SSSSyyyysssstttteeeemmmm VVVV ((((1111 JJJJaaaannnnuuuuaaaarrrryyyy 1111999999994444))))     TTTTKKKKNNNNEEEEWWWWSSSSBBBBIIIIFFFFFFFF((((1111))))



          the newsrc variable is not set explicitly).


     WWWWAAAATTTTCCCCHHHHIIIINNNNGGGG DDDDIIIIFFFFFFFFEEEERRRREEEENNNNTTTT NNNNEEEEWWWWSSSS SSSSEEEERRRRVVVVEEEERRRRSSSS
          To watch multiple servers, run tknewsbiff multiple times.
          (Since you need different .newsrc files and the servers have
          different newsgroups and article numbers anyway, there is no
          point in trying to do this in a single process.)

          You can point tknewsbiff at a different server with an
          appropriate argument.  The argument is tried both as a
          configuration file name and as a suffix to the string
          "~/.tknewsbiff-".  So if you want to watch the server
          "kidney", store the tknewsbiff configuration information in
          ~/.tknewsbiff-kidney".  The following two commands will both
          use that configuration file.


               tknewsbiff kidney
               tknewsbiff ~/.tknewsbiff-kidney


          In both cases, the actual server to contact is set by the
          value of the server variable in the configuration file.

          If no configuration file is found, the argument is used as
          the server to contact.  This allows tknewsbiff to be run
          with no preparation whatsoever.

          If the argument is the special keyword "active" (or ends in
          "/active"), it is used as the name of an active file.  This
          is in turn used to initialize the variable "active_file" so
          that tknewsbiff reads from the active file directly rather
          than using NNTP.

          Creating your own active file is a convenient way of testing
          your configuration file.  For example, after running the
          following command, you can repeatedly edit your active file
          and trigger the update-now command (either by pressing
          button 2 or setting the delay variable very low) to see how
          tknewsbiff responds.

          The active file must follow the format of a real active
          file.  The format is one newsgroup per line.  After the
          newsgroup name is the number of the highest article, the
          lowest article.  Lastly is the letter y or m.  m means the
          newsgroup is moderated.  y means posting is allowed.


     WWWWIIIINNNNDDDDOOOOWWWW
          When unread news is found, a window is popped up.  The
          window lists the names of the newsgroups and the number of



     Page 5                                          (printed 7/23/95)






     TTTTKKKKNNNNEEEEWWWWSSSSBBBBIIIIFFFFFFFF((((1111))))    UUUUNNNNIIIIXXXX SSSSyyyysssstttteeeemmmm VVVV ((((1111 JJJJaaaannnnuuuuaaaarrrryyyy 1111999999994444))))     TTTTKKKKNNNNEEEEWWWWSSSSBBBBIIIIFFFFFFFF((((1111))))



          unread articles in each (unless suppressed by the -display
          flag).  When there is no longer any unread news, the window
          disappears (although the process continues to run).


     BBBBUUUUTTTTTTTTOOOONNNNSSSS
          Button or key bindings may be assigned by bind commands.
          Feel free to change them.  The default bind commands are:


          bind .list <1> help
          bind .list <2> update-now
          bind .list <3> unmapwindow


          By default button 1 (left) is bound to "help".  The help
          command causes tknewsbiff to pop up a help window.

          By default, button 2 (middle) is bound to "update-now".  The
          update-now command causes tknewsbiff to immediately check
          for unread news.  If your news server is slow or maintains a
          very large number of newsgroups, or you have a large number
          of patterns in your configuration file, tknewsbiff can take
          considerable time before actually updating the window.

          By default, button 3 (right) is bound to "unmapwindow".  The
          unmapwindow command causes tknewsbiff to remove the window
          from the display until the next time it finds unread news.
          (The mapwindow command causes tknewsbiff to restore the
          window.)

          As an example, here is a binding to pop up an xterm and run
          rn when you hold down the shift key and press button 1 in
          the listing window.


          bind .list <Shift-1> {
               exec xterm -e rn &
          }


          Here is a similar binding.  However it tells rn to look only
          at the newsgroup that is under the mouse when you pressed
          it.  (The "display_list" variable is described later in this
          man page.)


          bind .list <Shift-1> {
               exec xterm -e rn [lindex $display_list [.list nearest %y]] &
          }





     Page 6                                          (printed 7/23/95)






     TTTTKKKKNNNNEEEEWWWWSSSSBBBBIIIIFFFFFFFF((((1111))))    UUUUNNNNIIIIXXXX SSSSyyyysssstttteeeemmmm VVVV ((((1111 JJJJaaaannnnuuuuaaaarrrryyyy 1111999999994444))))     TTTTKKKKNNNNEEEEWWWWSSSSBBBBIIIIFFFFFFFF((((1111))))



     OOOOTTTTHHHHEEEERRRR CCCCOOOOMMMMMMMMAAAANNNNDDDDSSSS AAAANNNNDDDD VVVVAAAARRRRIIIIAAAABBBBLLLLEEEESSSS
          Built-in commands already mentioned are: watch, ignore,
          display, help, update-now, unmapwindow, and mapwindow.

          Any Tcl and Tk command can also be given.  In particular,
          the list of newsgroups is stored in the list widget ".list",
          and the scroll bar is stored in the scrollbar widget
          ".scroll".  So for example, if you want to change the
          foreground and background colors of the newsgroup list, you
          can say:


               .list config -bg honeydew1 -fg orchid2


          These can also be controlled by the X resource database as
          well.  However, the configuration file allows arbitrarily
          complex commands to be evaluated rather than simple
          assignments.

          Certain Tcl/Tk commands can disrupt proper function of
          tknewsbiff.  These will probably be obvious to anyone who
          knows enough to give these commands in the first place.  As
          a simple example, the program assumes the font in the list
          box is of fixed width.  The newsgroups will likely not align
          if you use a variable-width font.

          The following variables are accessible and can be used for
          esoteric uses.  All other variables are private.  Private
          variables and commands begin with "_" so you don't need to
          worry about accidental collisions.

          The array "db" is a database which maintains information
          about read and unread news.  db($newsgroup,hi) is the
          highest article that exists.  db($newsgroup,seen) is the
          highest article that you have read.

          A number of lists maintain interesting information.
          "active_list" is a list of known newsgroups.  "seen_list" is
          a list of newsgroups that have been seen so far as the -new
          and -display flags are being processed.
          "previous_seen_list" is "seen_list" from the previous cycle.
          "ignore_list" is the list of newsgroup patterns to ignore.
          "watch_list" is the list of newsgroup patterns to watch.
          "display_list" is the list of newsgroup will be displayed at
          the next opportunity.


     UUUUPPPPDDDDAAAATTTTIIIINNNNGGGG YYYYOOOOUUUURRRR FFFFIIIILLLLEEEESSSS
          tknewsbiff automatically rereads your configuration file
          each time it wakes up to check for unread news.  To force
          tknewsbiff to reread the file immediately (such as if you



     Page 7                                          (printed 7/23/95)






     TTTTKKKKNNNNEEEEWWWWSSSSBBBBIIIIFFFFFFFF((((1111))))    UUUUNNNNIIIIXXXX SSSSyyyysssstttteeeemmmm VVVV ((((1111 JJJJaaaannnnuuuuaaaarrrryyyy 1111999999994444))))     TTTTKKKKNNNNEEEEWWWWSSSSBBBBIIIIFFFFFFFF((((1111))))



          are testing a new configuration or have just modified your
          newsrc file), press button 2 in the display (see BUTTONS
          above).


     CCCCAAAAVVVVEEEEAAAATTTTSSSS
          tknewsbiff defines the number of unread articles as the
          highest existing article minus the highest article that
          you've read.  So if you've read the last article in the
          newsgroup but no others, tknewsbiff thinks there are no
          unread articles.  (It's impossible to do any better by
          reading the active file and it would be very time consuming
          to do this more accurately via NNTP since servers provide no
          efficient way of reporting their own holes in the
          newsgroups.) Fortunately, this definition is considered a
          feature by most people.  It allows you to read articles and
          then mark them "unread" but not have tknewsbiff continue
          telling you that they are unread.


     UUUUNNNNWWWWAAAARRRRRRRRAAAANNNNTTTTEEEEDDDD CCCCOOOONNNNCCCCEEEERRRRNNNNSSSS
          Your news administrator may wonder if many people using
          tknewsbiff severely impact an NNTP server.  In fact, the
          impact is negligible even when the delay is very low.  To
          gather all the information it needs, tknewsbiff uses a
          single NNTP query - it just asks for the active file.  The
          NNTP server does no computation, formatting, etc, it just
          sends the file.  All the interesting processing happens
          locally in the tknewsbiff program itself.


     BBBBUUUUGGGGSSSS
          The man page is longer than the program.


     SSSSEEEEEEEE AAAALLLLSSSSOOOO
          "_E_x_p_l_o_r_i_n_g _E_x_p_e_c_t: _A _T_c_l-_B_a_s_e_d _T_o_o_l_k_i_t _f_o_r _A_u_t_o_m_a_t_i_n_g
          _I_n_t_e_r_a_c_t_i_v_e _P_r_o_g_r_a_m_s" by Don Libes, O'Reilly and Associates,
          January 1995.

     AAAAUUUUTTTTHHHHOOOORRRR
          Don Libes, National Institute of Standards and Technology













     Page 8                                          (printed 7/23/95)